swagger: '2.0'
info:
  version: 1.0.0
  title: Opintosuoritus API
  description: >
    'Tämä skeema on tuotettu Ristiinopiskelu-kärkihankkeelle 2017 ja perustuu
    SUOMEN VIRTUAALIYLIOPISTON OPETUSTIETOMÄÄRITYKSIÄ N:O 3 M3: Suoritusten
    tiedot, versioon 1.1 30.10.2009 jota on täydennetty KOSKI , ELMO ja
    VIRTA-määrityksillä.'
  contact:
    name: Pekka Järveläinen
    email: pj@csc.fi
  license:
    name: CC0
    url: 'https://creativecommons.org/licenses/by/4.0/'
consumes:
  - application/json
produces:
  - application/json
basePath: /v1
paths:
  /opintosuoritus/:
    post:
      description: >
        Opiskelijan opintosuorituksen siirto kuvaillen suorituksenkohteen
        sisällön, tavoitteet ja arviointikohteet. Suoritus voi olla mitä tahansa
        opintokokonaisuudesta KELA-kelpoiseen osasuoritukseen. Tässä ei
        määritellä suojauksia ja AAI, mutta ne on oltava tiukat. Esim. lista
        sallituista IP-osoitteista, joista APIa saa käyttää + avaimet +...
      operationId: suoritus
      produces:
        - application/json
      parameters:
        - name: M3-opintosuoritus
          in: body
          description: M3-opintosuoritus
          required: true
          schema:
            $ref: '#/definitions/m3'
      responses:
        '200':
          description: kuittaus
          schema:
            $ref: '#/definitions/kuittaus'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/errorModel'
definitions:
  m3:
    type: object
    required:
      - lähettäväorganisaatio
      - vastaanottavaorganisaatio
      - suorittaja
      - suoritukset
    description: M3
    properties:
      lähettäväorganisaatio:
        $ref: '#/definitions/organisaatio'
      vastaanottavaorganisaatio:
        $ref: '#/definitions/organisaatio'
      suorittaja:
        $ref: '#/definitions/suorittaja'
      suoritukset:
        $ref: '#/definitions/suoritukset'
      lähetysaika:
        type: string
        format: date-time
        description: 'M0 0.3 RFC 3339, section 5.6'
      purkuaika:
          type: string
          format: date-time
          description: >
            jira CSCRISTIINOPISKELU-184 viestin purkuhetken aikaleima
            on mahdoton alkuperäiselle lähettäjälle, mutta matkalla...
  suorittaja:
    type: object
    required:
      - oid
    properties:
      oid:
        type: string
        description: oppijanumero Oid
      henkilötunnus:
        type: string
        description: M3 1.1
      generoituhenkilötunnus:
        type: string
        description: M0 1.2 Ei saa käyttää viralliselle
      vastaanottotunnus:
        type: string
        description: M3 1.2 Jos tiedetään tunnus vastaanottavassa organisaatiossa
      lähdetunnus:
        type: string
        description: M3 1.3 oma opiskelijanumero tai tunnus
      eppn:
        type: string
        description: 'EduPerson Principal Name (Jaakon sähköposti 5 Feb 2018 09:16:40)' 
      etunimi:
        type: string
        description: M3 1.4
      sukunimi:
        type: string
        description: M3 1.5
  suoritukset:
    type: array
    items:
      $ref: '#/definitions/suoritus'
  suoritus:
    type: object
    required:
      - organisaatio
      - suoritus
      - suorituskielet
      - tila
      - laajuus
      - arvostelu
      - nimi
      - suorituspäivämäärä
      - hyväksyjät
      - suorituksenvastuuorganisaatio
      - status
    properties:
      organisaatio:
        type: string
        description: >
          M3 1.6.1.2 oid, muodostaa suorituksen tunnuksen kanssa yksikäsitteisen
          avaimen
      suoritus:
        type: string
        description: >
          M3 1.6.1.2 muodostaa organisaation tunnuksen kanssa yksikäsitteisen
          avaimen
      opintojakson arviointikohteen toteutus:
        type: string
        description: Jaakon maili 2018-01-24 Näitä käytettävä osasuorituksissa
      opintojakson arviointikohde:
        type: string
        description: Jaakon maili 2018-01-24 Näitä käytettävä osasuorituksissa
      opintojakson toteutuksen osa:
        type: string
        description: Jaakon maili 2018-01-24 Näitä käytettävä osasuorituksissa
      opintojaksontoteutus:
        type: string
        description: M3 1.6.2.1
      opintokokonaisuudentoteutus:
        type: string
        description: M3 1.6.2.2
      opintojakso:
        type: string
        description: M3 1.6.2.3
      opintokokonaisuus:
        type: string
        description: M3 1.6.2.4
      vapaaaopintokokonaisuus:
        type: string
        description: M3 1.6.2.5
      tutkinto:
        type: string
        description: M3 1.6.2.7
      suorituskielet:
        type: array
        items:
          type: string
          minLength: 2
          maxLength: 2
        description: M3 1.6.3 ISO 639 kaksikirjaiminen
      tila:
        type: string
        description: M3 1.6.4
        enum:
          - Ei osallistunut
          - Yritys hylätty
          - Hyväksytty
          - Kesken
      laajuus:
        type: number
        format: float
        description: M3 1.6.5 tarkemmin 1.6.5.2 Opintopisteitä max 2 desimaalia
      arvostelu:
        $ref: '#/definitions/arvostelu'
      nimi:
        type: string
        description: M3 1.6.7 Kurssin/koulutusohjelman nimi
      suoritustapa:
        type: string
        description: M3 1.6.8
      suorituspäivämäärä:
        type: string
        format: date
        description: M3 1.6.9 ajankohta ISO 8601
      hyväksyjät:
        type: array
        items:
          $ref: '#/definitions/henkilö'
      suorituksenvastuuorganisaatio:
        $ref: '#/definitions/organisaatio'
      sisältö:
        type: string
        description: M3 1.6.12
      lisätietoja:
        type: string
        description: M3 1.6.13
      sisältyvätsuoritukset:
        type: array
        items:
          type: string
        description: M3 1.6.14 esim. opintokokonaisuuteen sisältyvät jaksot
      status:
        type: string
        description: >
          uutta! 2. tarkoittaa onnistunutta korotusta ja 3. virhettä 3
          Käyttäjätarinat kohta 3.1
        enum:
          - 1. uusi suoritus
          - '2. uusi suoritus, joka korvaa entisen'
          - 3. vanhan korjaus
          - 4. suorituksen poisto
      osasuoritus:
        type: boolean
        description: uutta!
      laji:
        type: string
        description: uutta virrasta!
        enum:
          - 1 tutkinto
          - 2 muu opintosuoritus
          - 3 ei huomioitavaa
          - 4 oppilaitoksen sisäinen
      opiskeluoikeus:
        type: string
        description: >
          uutta, viite opiskeluoikeuteen, koska näitäkin saattoi olla monta
          Teknisen vaatimusmäärittelyn kohta 2.1.6
  arvostelu:
    type: object
    required:
      - arvosteluasteikko
      - arvosana
    properties:
      arvosteluasteikko:
        type: object
        description: >-
          M3 1.6.6
          https://confluence.csc.fi/display/VIRTA/Tietovarannon+koodistot#Tietovarannonkoodistot-Arvosana-asteikot,Vitsordsskalor
          M2 taulukko 4 1.2 EvaluationType.Numerical or Enumerated or system or
          Grading table based on the ECTS Grading Table (EGT)
        properties:
          asteikko:
            type: string
            enum:
              - Viisiportainen
              - Hyväksytty
              - Toinen kotimainen
              - Näytetyö
              - Tutkielma
              - EGT
              - EiKäytössä
              - Muu
            description: EGT = ECTS Grading Table
      arvosana:
        type: string
        enum:
          - HYV
          - 1
          - 2
          - 3
          - 4
          - 5
          - TT
          - HT
          - KH
          - A
          - B
          - 'N'
          - C
          - M
          - E
          - L
          - Arvosana ei käytössä
        description: 'kaikki yhdistelmät eivät ole laillisia, noudatettava virta määritystä'
      egt:
        type: string
        description: vain tämä saa olla vapaa merkkijono
      selite:
        type: string
        description: M2 taulukko 4 1.2.2
  organisaatio:
    type: object
    required:
      - tunniste
      - organisaation nimi
    properties:
      tunniste:
        type: string
        description: oid
      organisaation nimi:
        type: string
        description: M2 4.1.2
      yksikön nimi:
        type: string
        description: M2 4.1.3 "Lääketieteellinen tiedekunta"
      nimiselite:
        type: string
        description: M2 4.1.4 "Patologian laitos"
      postiosoite:
        $ref: '#/definitions/osoite'
      käyntiosoite:
        $ref: '#/definitions/osoite'
      puhelin:
        $ref: '#/definitions/puhelin'
      PIC:
        type: number
        format: int32
        description: 'Erasmus, esim. 934620221'
      ErasmusID:
        type: string
        description: esim. (SF KUOPIO08)
      HEI:
        type: string
        description: esim. SAVONIA-AMMATTIKORKEAKOULU OY
      ErasmusCharterCode:
        type: string
        description: esim. 9571-EPP-1-2014-1-FI-EPPKA3-ECHE
      organisaatiokoodi:
        type: number
        format: int32
        description: 'Erasmus, esim. 02537'
      organisaatio:
        type: string
        description: 'Erasmus, esim. SAVONIA'
      url:
        type: string
        description: M 4.1.10 Erasmus pakollinen
  osoite:
    type: object
    properties:
      katu:
        type: string
        description: M2 4.1.5/6.1
      postinumero:
        type: number
        format: int32
        description: M2 4.1.5/6.2
      postitoimipaikka:
        type: string
        description: M2 4.1.5/6.3
      maa:
        type: string
        description: M2 4.1.5/6.4
  puhelin:
    type: object
    required:
      - numero
    properties:
      numero:
        type: string
        description: M2 4.1.7.1 kansainvälinen +358 muoto
      selite:
        type: string
        description: M2 4.1.7.2 "esim. kanslia tai työ"
    description: M3 2.7
  yhteistyoverkosto:
    type: object
    required:
      - tunnus
      - nimi
    properties:
      tunnus:
        type: string
        description: URI M2 1.1.5.1
      nimi:
        type: string
        description: M2 1.1.5.2
  errorModel:
    type: object
    required:
      - code
      - message
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
  henkilö:
    type: object
    required:
      - tunniste
      - nimike
      - etunimi
      - sukunimi
    description: Huomattava tässa skeemassa etu- ja sukunimi ovat pakolliset.
    properties:
      tunniste:
        type: string
        description: M2 3.1.1.1 Oid
      henkilötunnus:
        type: string
        description: >-
          M2 3.1.1.2 Ehdottomasti ei pakollinen, konsultoi juristia ennen
          käyttöä
      nimike:
        type: string
        description: M3 2.2 Pakollinen
      etunimi:
        type: string
        description: M3 2.3 mutta pakollinen!
      sukunimi:
        type: string
        description: M2 2.4 mutta pakollinen!
      sähköposti:
        type: string
        format: email
        description: M3 2.5
      verkkosivu:
        type: string
        description: M3 2.6 URL
      puhelin:
        $ref: '#/definitions/puhelin'
      organisaatio:
        $ref: '#/definitions/organisaatio'
  kuittaus:
    type: object
    required:
      - code
    properties:
      code:
        type: integer
        format: int32
